<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <meta name="generator" content="rustdoc">
    <title>Native Windows GUI guide - Controls</title>

    <link rel="stylesheet" type="text/css" href="style/rustbook.css">
    <link rel="stylesheet" type="text/css" href="style/pygments.css">
    <link rel="stylesheet" type="text/css" href="style/nwg.css">
</head>
<body class="rustdoc">
<!--[if lte IE 8]>
<div class="warning">
    This old browser is unsupported and will most likely display funky
    things.
</div>
<![endif]-->

<!-- NAV BEGIN -->
<div id="nav">
    <button id="toggle-nav">
        <span class="sr-only">Toggle navigation</span>
        <span class="bar"></span>
        <span class="bar"></span>
        <span class="bar"></span>
    </button>
</div>

    
<div id='toc' class='mobile-hidden'>
<ul class='chapter'>
<li><a href='index.html'><b>1.</b> Introduction</a>
</li>
<li><a href='getting_started.html'><b>2.</b> Getting Started</a>
</li>

<li><a href="basics.html"><b>3.</b> Basics </a>
<ul class="section">
    <li><a href="controls.html"><b>3.1.</b> Controls </a></li>
    <li><a href="events.html"><b>3.2.</b> Events </a></li>
    <li><a href="helper.html"><b>3.3.</b> Helpers </a></li>
    <li><a href="small.html"><b>3.4.</b> Small application layout </a></li>
    <li><a href="limitations.html"><b>3.5.</b> Limitations </a></li>
    <li><a href="distribute.html"><b>3.6.</b> Distributing </a></li>
    <li><a href="features.html"><b>3.7.</b> Features </a></li>
</ul>
</li>

<li><a href="intermediate.html"><b>4.</b> Intermediate </a>
<ul class="section">
    <li><a href="layouts.html"><b>4.1.</b> Layouts </a></li>
    <li><a href="resources.html"><b>4.2.</b> Resources </a></li>
    <li><a href="dialogs.html"><b>4.3.</b> Dialogs </a></li>
    <li><a href="localization.html"><b>4.4.</b> Internationalization </a></li>
</ul>
</li>

<li><a href="advanced.html"><b>5.</b> Advanced </a>
<ul class="section">
    <li><a href="partial.html"><b>5.1.</b> Partials ui </a></li>
    <li><a href="dynamic_control.html"><b>5.2.</b> Dynamic control </a></li>
    <li><a href="dynamic_event.html"><b>5.3.</b> Dynamic events </a></li>
    <li><a href="multithreading.html"><b>5.4.</b> Multithreading </a></li>
</ul>
</li>

<li><a href="derive.html"><b>6.</b> Native-windows-derive </a>
<ul class="section">
    <li><a href="nwd_basics.html"><b>6.1.</b> Basics </a></li>
    <li><a href="nwd_controls.html"><b>6.1.</b> Controls </a></li>
    <li><a href="nwd_resources.html"><b>6.2.</b> Resources </a></li>
    <li><a href="nwd_events.html"><b>6.3.</b> Events </a></li>
    <li><a href="nwd_layouts.html"><b>6.4.</b> Layouts </a></li>
    <li><a href="nwd_partial.html"><b>6.5.</b> Partials </a></li>
</ul>
</li>

<li><a href="low.html"><b>7.</b> Low level stuff </a>
    <ul class="section">
        <li><a href="low_events.html"><b>7.1.</b> Raw event handling </a></li>
        <li><a href="extern_wrapping.html"><b>7.2.</b> Raw control handle </a></li>
    </ul>
</li>

</ul>
</div>
<!-- NAV END -->

<div id='page-wrapper'>
    <div id='page'>

        <h1 class="title">Native Windows GUI: Controls</h1>

        Controls are UI elements that can be interacted with. Native windows GUI wraps over 25 different controls in a safe rust-friendly interface.
        This section explains the basics of using NWG controls.
        <br/><br/>

        To learn how to use controls with <code>native-windows-derive</code> see <a href="nwd_controls.html">the derive section</a>
        <br><br/>

        <h3>Control builder</h3>  
        Controls are created using a <b>builder</b> API. On each control type, the method <code>builder</code> can be
        called in order to instantiate a builder object. Builder names use the following format: <code>[ControlName]Builder</code>. Ex: (<code>ButtonBuilder</code>).
        <br/><br/>

        Each control documentation enumerates the properties accepted by the builder.
        <br><br>

<div class="highlight"><pre style="width: auto;"><span></span><span class="k">use</span><span class="w"> </span><span class="n">native_windows_gui</span><span class="w"> </span><span class="k">as</span><span class="w"> </span><span class="n">nwg</span><span class="p">;</span><span class="w"></span>
<span class="k">fn</span> <span class="nf">build_button</span><span class="p">(</span><span class="n">button</span>: <span class="kp">&amp;</span><span class="nc">mut</span><span class="w"> </span><span class="n">nwg</span>::<span class="n">Button</span><span class="p">,</span><span class="w"> </span><span class="n">window</span>: <span class="kp">&amp;</span><span class="nc">nwg</span>::<span class="n">Window</span><span class="p">,</span><span class="w"> </span><span class="n">font</span>: <span class="kp">&amp;</span><span class="nc">nwg</span>::<span class="n">Font</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">    </span><span class="n">nwg</span>::<span class="n">Button</span>::<span class="n">builder</span><span class="p">()</span><span class="w"></span>
<span class="w">        </span><span class="p">.</span><span class="n">text</span><span class="p">(</span><span class="s">&quot;Hello&quot;</span><span class="p">)</span><span class="w"></span>
<span class="w">        </span><span class="p">.</span><span class="n">flags</span><span class="p">(</span><span class="n">nwg</span>::<span class="n">ButtonFlags</span>::<span class="n">VISIBLE</span><span class="w"> </span><span class="o">|</span><span class="w"> </span><span class="n">nwg</span>::<span class="n">ButtonFlags</span>::<span class="n">CHECK</span><span class="p">)</span><span class="w"></span>
<span class="w">        </span><span class="p">.</span><span class="n">font</span><span class="p">(</span><span class="nb">Some</span><span class="p">(</span><span class="n">font</span><span class="p">))</span><span class="w"></span>
<span class="w">        </span><span class="p">.</span><span class="n">parent</span><span class="p">(</span><span class="n">window</span><span class="p">)</span><span class="w"></span>
<span class="w">        </span><span class="p">.</span><span class="n">build</span><span class="p">(</span><span class="n">button</span><span class="p">);</span><span class="w"></span>
<span class="p">}</span><span class="w"></span>
</pre></div>
            

        <h3>Control methods</h3>
        
        NWG wraps almost every controls functionalities behind object methods. Fonctionnalities usually come in get/set pair.
        The syntax used is <code>[property]()</code> for getters and <code>set_[property](value)</code> for setters. Example:
        <br><br>

<div class="highlight"><pre style="width: auto;"><span></span><span class="k">fn</span> <span class="nf">test</span><span class="p">(</span><span class="n">button</span>: <span class="nc">&Button</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">    </span><span class="n">button</span><span class="p">.</span><span class="n">visible</span><span class="p">();</span><span class="w"></span>
<span class="w">    </span><span class="n">button</span><span class="p">.</span><span class="n">set_visible</span><span class="p">(</span><span class="kc">true</span><span class="p">);</span><span class="w"></span>
<span class="p">}</span><span class="w"></span>
</pre></div>

        <br>

        Methods of NWG never takes a mutable borrow. This is because most methods maps directy to a single winapi call.
        And because the application data will almost certaintly be behind a <code>Rc</code>, having to put each control behind a refcell would be HELL.
        <br><br>

        Every NWG controls implements the <code>Default</code> trait. A control created from this is marked as <b>uninitialized</b>.
        Calling the methods of an uninitialized control will cause a <b>panic</b>.
        <br><br>

        <h3>Window / Container controls</h3> 

        Most controls in NWG cannot hold children. Those that can are called "container controls". This includes <b>Window</b>, <b>Tab Container</b>,
        and <b>Tab</b>. TabContainer should only contains tab controls.<br><br>

        Container controls can also use <b>layouts</b>. More on that in <a href="file:///C:/Users/Gab/Documents/projects/native-windows-gui/native-windows-docs/layouts.html">the layout section</a>
        <br><br>

        The window control is be the base of any GUI application. It represents a top level system window. Every NWG application will have a window.
        This also includes system tray applications. In this case, the window should be a <code>MessageWindow</code>, an invisible window that only dispatch messages.
        <br><br>

        Window controls are highly customizable. System decorated window (aka normal window), popup window, and transparent window can be created by selecting the right <code> WindowFlags</code>.
        <br><br>

<div class="highlight"><pre style="width: auto;"><span></span><span class="n">nwg</span>::<span class="n">Window</span>::<span class="n">builder</span><span class="p">()</span><span class="w"></span>
<span class="w">    </span><span class="p">.</span><span class="n">flags</span><span class="p">(</span><span class="n">nwg</span>::<span class="n">WindowFlags</span>::<span class="n">WINDOW</span><span class="w"> </span><span class="o">|</span><span class="w"> </span><span class="n">nwg</span>::<span class="n">WindowFlags</span>::<span class="n">VISIBLE</span><span class="p">)</span><span class="w"></span>
<span class="w">    </span><span class="p">.</span><span class="n">size</span><span class="p">((</span><span class="mi">300</span><span class="p">,</span><span class="w"> </span><span class="mi">115</span><span class="p">))</span><span class="w"></span>
<span class="w">    </span><span class="p">.</span><span class="n">position</span><span class="p">((</span><span class="mi">300</span><span class="p">,</span><span class="w"> </span><span class="mi">300</span><span class="p">))</span><span class="w"></span>
<span class="w">    </span><span class="p">.</span><span class="n">title</span><span class="p">(</span><span class="s">&quot;Basic example&quot;</span><span class="p">)</span><span class="w"></span>
<span class="w">    </span><span class="p">.</span><span class="n">build</span><span class="p">(</span><span class="o">&amp;</span><span class="k">mut</span><span class="w"> </span><span class="n">data</span><span class="p">.</span><span class="n">window</span><span class="p">)</span><span class="o">?</span><span class="p">;</span><span class="w"></span>
</pre></div>
            

        <h3>Controls hierarchy</h3>  

        All non-window control require a parent. If no parent is defined when building a new control, the build function will return a <code>NwgError::ControlCreationError</code>.
        <br><br>

        <h3>Control events</h3>  

        Controls can raise <code>Events</code> when interacted with. The events that can be raised by a control are
        in the their documentation.<br/><br/>

        All controls have specific events (ex: <code>OnButtonClick</code>) and generic events that are shared (ex: <code>OnPaint</code>).<br/><br/>

        More on this in the next section

        <br><br>

        <h3>Implementation</h3>

        To keep compile time low, most controls are feature-gated. 
        <br/><br/>

        Every control is implemented as a wrapper over a low level window handle. As such, <b>most*</b> of them only take the size of a pointer.<br><br>
        
        Some built-in controls lacks critical feature on their own. To fix this, nwg extends those controls with <a href="low_events.html">raw events handlers</a>.
        <br><br>

        Also, controls that support custom collections (ex: ListBox and ComboBox) also uses Rust collections internally to store the rust data.
        <br/><br/>

        <h3>Freeing</h3>

        Controls implement <code>Drop</code> and are freed when they go out of scope.

        <br><br><br><br>


    </div>
</div>

<script src="style/rustbook.js"></script>
</body>
</html>
